Kiro CLI

Comprehensive Tutorial · From Installation to Mastery

v1.26 · February 2026

1. Introduction to Kiro CLI

Kiro CLI is a powerful command-line tool that brings AI-powered development directly to your terminal. Built on advanced AI models, it understands your codebase, writes and reviews code, automates workflows, and helps you ship faster without leaving the command line.

Whether you are debugging a production server, working in an SSH session, or simply prefer the terminal, Kiro CLI keeps you in your flow state while providing intelligent assistance.

Kiro CLI Architecture Diagram

1.1 What Can Kiro CLI Do?

1.2 Supported Languages

Kiro CLI supports 18+ programming languages including Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Lua, Elixir, Bash, and TSX.

2. Installation & Setup

Kiro CLI Workflow Diagram
Internal Setup Guide

For Mumzworld team members, Osman has put together a detailed step-by-step setup guide covering AWS Builder ID creation, Kiro CLI installation, and workspace configuration: Amazon Q Developer / Kiro Setup Guide. Thanks Osman!

2.1 Prerequisites

Before installing Kiro CLI, you need an AWS Builder ID. Visit the AWS Builder ID page and select "Sign up with Builder ID" to create one. This is free and takes just a few minutes.

2.2 Installing Kiro CLI

macOS and Linux (recommended):

curl -fsSL https://cli.kiro.dev/install | bash

Linux AppImage (portable, no root required)

# Download the AppImage
wget https://desktop-release.q.us-east-1.amazonaws.com/latest/kiro-cli.appimage

# Make it executable
chmod +x kiro-cli.appimage

# Run directly
./kiro-cli.appimage

Ubuntu / Debian (DEB package)

wget https://desktop-release.q.us-east-1.amazonaws.com/latest/kiro-cli.deb
sudo dpkg -i kiro-cli.deb
sudo apt-get install -f
kiro-cli

Linux ZIP (manual install)

# Download and unzip
unzip kirocli.zip

# Install to ~/.local/bin (default)
./kirocli/install.sh
System Requirements - Kiro CLI requires glibc 2.34 or newer (included in most Linux distributions since 2021). For older systems, use the musl-based version indicated by -musl.zip in the filename. Supported architectures: x86_64 and ARM aarch64. Check your glibc version with ldd --version.

Uninstalling

# macOS
kiro-cli uninstall

# Ubuntu / Debian
sudo apt-get remove kiro-cli
sudo apt-get purge kiro-cli

2.3 Authentication

After installation, run kiro-cli and it will open your web browser for authentication. Sign in with your AWS Builder ID to complete the setup.

# Start Kiro CLI for the first time
kiro-cli

# It will open your browser for authentication
# Follow the on-screen instructions to sign in
Enterprise Users - Kiro CLI v1.25.1+ supports authentication with Okta or Microsoft Entra ID credentials. Enterprise teams can connect alongside AWS IAM Identity Center for centralized access management.

2.4 Proxy Support

Kiro CLI (v1.8.0+) automatically respects standard proxy environment variables, making it compatible with enterprise environments that use proxy servers.

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# For authenticated proxies, include credentials in the URL
export HTTPS_PROXY=http://user:password@proxy.company.com:8080

3. Getting Started with Chat

The primary way to interact with Kiro CLI is through its chat interface. When you start kiro-cli without any subcommand, it defaults to chat mode.

Chat Session Lifecycle kiro-cli or kiro-cli chat Chat Session Type messages Use slash commands /editor Ctrl+J /chat save /chat load --resume Continue previous session by directory --agent name Use specific agent --resume-picker Interactive chooser

3.1 Starting a Chat Session

# Start a chat session (default)
kiro-cli chat

# Or simply
kiro-cli

# Start with a specific agent
kiro-cli chat --agent my-agent

# Resume the last conversation in this directory
kiro-cli chat --resume

# Interactive session picker to choose which conversation to resume
kiro-cli chat --resume-picker

Multi-line Input

For longer or more complex prompts, use the built-in editor support:

# Open your default editor (vi) to compose a message
/editor

# Or press Ctrl+J to open the editor inline

# Reply to the last assistant message with quoted context
/reply
Editor Customization - The default editor is vi. Customize it by setting the EDITOR environment variable (e.g., export EDITOR=nano).

Saving and Loading Conversations

# Save current conversation
/chat save ~/my-sessions/review-session -f

# Load a previous conversation (replaces current chat)
/chat load ~/my-sessions/review-session
Note - The tilde (~) cannot be used for home directory in save/load paths. Use the full path or a relative path. Loading a conversation replaces the current chat regardless of the source directory.

3.2 Model Selection

Model Best For Key Strengths
Auto (Default) General development Intelligent model routing, best quality per task
Claude Opus 4.6 Complex, large codebases Careful planning, sustained tasks, self-debugging
Claude Sonnet 4.5 Extended thinking tasks Deep reasoning for complex problems
Claude Sonnet 4 Everyday coding Fast and capable for common tasks
Claude Haiku 4.5 Quick tasks Fastest responses, lower token usage
Changing Models - You can ask Kiro to change your default model during a chat session, or use Tab completion for dynamic model selection (v1.26.0+).

3.3 Inline File References

Starting with v1.26.0, you can reference files directly in your messages using the @path syntax.

# Reference a specific file
> Look at @src/utils/auth.ts and find the login function

# Reference multiple files
> Compare @package.json with @package-lock.json

4. Slash Commands Reference

Slash commands are special commands you type during a chat session that start with a forward slash (/). They provide quick access to various Kiro CLI features.

Command Description Example
/help Switch to Help Agent or ask a question /help How do I configure MCP?
/editor Open your default editor for multi-line input /editor
/reply Reply to last response with quoted context in editor /reply
/chat save Save conversation to a file (-f to overwrite) /chat save ~/session -f
/chat load Load a previously saved conversation /chat load ~/session
/context Manage context files and view usage /context add src/config.ts
/mcp View active MCP servers /mcp
/tools Display tools with token counts /tools
/agent generate Create a new agent configuration /agent generate
/agent swap Switch to a different agent /agent swap my-agent
/prompt View and use saved prompts /prompt list
/code init Enable LSP code intelligence /code init
/save Save conversation history /save my-session
/load Load a previous conversation /load my-session
/experiment Toggle experimental features /experiment
/todo resume Resume incomplete task lists /todo resume
/clear Clear conversation history /clear
/quit Exit Kiro CLI /quit
Token Visibility - The /tools command now shows estimated token counts for each tool and totals per origin (v1.26.0+), helping you understand how much of your context window is being used by MCP servers and native tools.

5. Built-in Tools

Kiro CLI comes with a set of built-in tools that the AI agent uses to interact with your system.

Tool Internal Name What It Does
Shell execute_bash Run shell commands in your terminal
File Read fs_read Read files and directory contents
File Write fs_write Create and edit files
Code Intelligence code Symbol search, pattern matching, AST analysis
Grep grep Search file contents with regex patterns
Glob glob Find files by name patterns
AWS CLI use_aws Execute AWS CLI commands
Web Search web_search Search the web for information
Web Fetch web_fetch Fetch content from URLs
Subagent use_subagent Delegate tasks to specialized subagents
Knowledge knowledge Knowledge base operations (experimental)
Tool Permissions - Use the /tools command to manage permissions for individual tools. You can pre-approve trusted tools in your agent configuration to eliminate permission prompts during focused work sessions.

6. Code Intelligence

One of Kiro CLI's most powerful features is its two-tier code intelligence system. It combines tree-sitter (built-in) for immediate code understanding with optional LSP integration for enhanced precision.

Code Intelligence Diagram

6.1 Tree-sitter (Built-in)

Tree-sitter provides out-of-the-box code intelligence for 18 languages with no setup required. It supports fuzzy symbol matching, document symbols, and definition lookup. With incremental loading, it can efficiently handle codebases with millions of tokens.

Key Operations:

Operation Description
search_symbols Find symbol definitions by name with fuzzy matching
lookup_symbols Get detailed information for specific symbols
get_document_symbols List all symbols in a specific file
pattern_search AST-based structural search across your codebase

6.2 LSP Integration (Optional)

For enhanced precision, enable Language Server Protocol integration:

# Initialize LSP for your workspace
/code init

# This will:
# 1. Detect languages from project markers (package.json, Cargo.toml, etc.)
# 2. Start appropriate language servers
# 3. Enable enhanced features

LSP adds: find references, go to definition, hover documentation, rename refactoring, and diagnostics. Pre-configured for TypeScript, Rust, Python, Go, Java, Ruby, and C/C++.

Important - Code intelligence is configured per workspace, not globally. Each project maintains its own LSP settings. Delete lsp.json from your project root to disable it.

7. Custom Agents

Custom agents let you define specialized AI configurations for specific workflows, reducing interruptions by pre-approving trusted tools and automatically including relevant context.

Agents Flow Diagram

7.1 Creating a Custom Agent

# Interactive agent creation
/agent generate

# Or via CLI command
kiro-cli agent create my-agent

# List all available agents
kiro-cli agent list

# Switch to a different agent
/agent swap my-agent

7.2 Agent Configuration File

Example code review agent:

{
  "name": "code-reviewer",
  "description": "Code review agent focused on quality and security",
  "tools": ["fs_read", "code", "grep", "glob", "@git"],
  "allowedTools": ["fs_read", "code", "grep", "glob"],
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"]
    }
  },
  "shellSettings": {
    "allowedCommands": ["git diff.*", "git log.*", "git show.*"],
    "deniedCommands": ["rm -rf.*", "git push.*"]
  },
  "hooks": {
    "userPromptSubmit": [
      {
        "command": "echo 'Focus: code quality, security, best practices'",
        "timeout_ms": 5000
      }
    ]
  }
}

7.3 Agent Scopes

Scope Location Best For
Global ~/.kiro/agents/ Personal productivity agents available across all projects
Project .kiro/agents/ Project-specific workflows shared via version control

7.4 Key Configuration Options

Field Purpose
tools List of built-in and MCP tools the agent can use
allowedTools Tools that run without permission prompts
mcpServers MCP server definitions for external tool access
hooks Commands to run at lifecycle trigger points
shellSettings Control which shell commands are allowed/denied
toolAliases Rename tools to avoid conflicts or for convenience
availableAgents Control which agents can be spawned as subagents
trustedAgents Subagents that run without permission prompts
includeMcpJson Whether to include workspace/user MCP configs
Tool Aliases - If multiple MCP servers provide tools with the same name, use toolAliases to disambiguate them and avoid naming collisions.

7.5 Example Agents

Minimal Agent — Start Here

Save this as .kiro/agents/helper.json in your project root. It gives you a basic agent with file access and shell commands pre-approved so you can work without permission prompts:

{
  "name": "helper",
  "description": "General-purpose dev assistant with file and shell access",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "grep",
    "glob",
    "code"
  ],
  "allowedTools": [
    "fs_read",
    "fs_write",
    "grep",
    "glob",
    "code"
  ],
  "resources": [
    "file://.kiro/steering/**/*.md"
  ]
}
How to use it

kiro-cli chat --agent helper — or switch mid-session with /agent swap helper

Notice that execute_bash is in tools but not in allowedTools — this means shell commands are available but still require your approval each time. Only add tools to allowedTools when you fully trust them to run unattended.

More Agent Examples

8. Skills

Skills are reusable bundles of tools, knowledge, and workflows for specialized tasks. They activate dynamically when you invoke them via slash commands, giving the agent procedural knowledge for specific jobs.

8.1 How Skills Work

Type / in the chat input to see available skills as slash commands. Selecting a slash command loads the full skill instructions into the agent's context. Skills can include:

8.2 Skill Scopes

Scope Location Use Case
Workspace .kiro/skills/ Project-specific workflows like deployment procedures
Global ~/.kiro/skills/ Personal workflows you use regardless of project

8.3 Discovering Skills on skills.sh

skills.sh is an open community directory with 69,000+ reusable skills for AI agents, including Kiro CLI. You can browse, search, and install skills with a single command.

Installing a Skill

# Install a skill from the community directory
npx skills-add owner/skill-name

# Examples:
npx skills-add anthropics/find-skills
npx skills-add vercel/react-best-practices
npx skills-add frontend-design

Installed skills appear as slash commands in your chat session. Type / to see all available skills.

Popular Skills Worth Installing

Skill What It Does
find-skills Helps discover and install more skills based on what you need
react-best-practices React/Next.js patterns, RSC boundaries, data fetching conventions
frontend-design Production-grade UI design with creative, polished code generation
web-design-guidelines Web design standards and accessibility patterns
ast-grep Structural code search using AST patterns across your codebase
Browse the full catalog

Visit skills.sh to search by category, see trending skills, and filter by agent compatibility. The directory supports 18+ AI agents including Kiro CLI.

8.4 Creating Custom Skills

Skills are directories containing instruction files and optional configuration. A minimal skill is just a markdown file with instructions:

# Create a workspace-level skill
mkdir -p .kiro/skills/deploy

# The skill instruction file
# .kiro/skills/deploy/instructions.md
# ─────────────────────────────────────
# Deployment Procedure
#
# 1. Run the test suite: npm test
# 2. Build the production bundle: npm run build
# 3. Deploy to staging: ./scripts/deploy.sh staging
# 4. Run smoke tests against staging
# 5. If smoke tests pass, deploy to production: ./scripts/deploy.sh production
# 6. Verify health checks at /api/health

Once created, invoke it with /deploy in your chat session.

Skills vs Agents — Skills bundle MCP tools with knowledge and workflows, activating dynamically when invoked. Agents define broader configurations including tools, permissions, and execution settings. Use skills for task-specific knowledge and agents for workflow-specific environments.

9. MCP (Model Context Protocol)

MCP is an open standard that allows Kiro CLI to communicate with external servers for specialized tools and information — like a plugin system.

MCP Diagram

9.1 Configuration Files

Level File Location Scope
Workspace .kiro/settings/mcp.json Project-specific servers
User/Global ~/.kiro/settings/mcp.json Available across all projects
Agent Inside agent JSON config Agent-specific servers

9.2 Local Server Configuration

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      }
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-bravesearch"],
      "env": {
        "BRAVE_API_KEY": "env_variable_ref"
      }
    }
  }
}

9.3 Remote Server Configuration

{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token_ref",
        "X-Custom-Header": "value"
      }
    }
  }
}

9.4 Managing MCP Servers

# Add a new MCP server with full options
kiro-cli mcp add \
  --name "awslabs.aws-documentation-mcp-server" \
  --scope global \
  --command "uvx" \
  --args "awslabs.aws-documentation-mcp-server@latest" \
  --env "FASTMCP_LOG_LEVEL=ERROR"

# Add to workspace scope
kiro-cli mcp add --name myserver --scope workspace

# Add to specific agent
kiro-cli mcp add --name myserver --agent myagent

# View active servers in chat
/mcp

MCP Tool Validation Requirements

Security Best Practice - Always use environment variable references instead of hardcoding sensitive values. Never commit configuration files with credentials to version control.

9.5 Enterprise Governance

For enterprise teams, Kiro CLI supports MCP Registry mode. Administrators can create a JSON allowlist of approved servers, serve it over HTTPS, and configure it. When registry mode is active, users cannot add custom servers.

10. Hooks

Hooks let you execute custom commands at specific points during the agent lifecycle.

Hooks Lifecycle Diagram
Hook Lifecycle & Trigger Flow 1 AgentSpawn Agent starts Load context 2 UserPromptSubmit User sends msg Validate / inject 3 PreToolUse Before tool runs Validate / block exit 2 = block 4 PostToolUse After tool runs Log / format 5 Stop Response done Test / format / clean repeats per tool call Exit codes: 0 Success (STDOUT to context) 2 Block tool (PreToolUse only) ? Warning shown

10.1 Hook Trigger Points

Trigger When It Fires Common Use
agentSpawn When the agent starts Load environment, initialize context
userPromptSubmit When user sends a message Validate input, inject context
preToolUse Before a tool executes Security checks, input validation
postToolUse After a tool executes Format output, log results
stop When the assistant completes its response Compilation, testing, formatting, cleanup

Exit Code Behavior

Exit Code Behavior
0 Success. STDOUT is captured and added to context. For PreToolUse, the tool proceeds.
2 PreToolUse only: blocks tool execution. STDERR is returned to the LLM as feedback.
Other Failure warning shown to the user. Tool execution is not affected.

Hook Event Data (JSON via STDIN)

Hooks receive a JSON payload via STDIN containing:

Tool Matching with matcher

Use the matcher field to target specific tools:

Matcher Pattern Example Matches
Canonical name "fs_write", "execute_bash" Exact built-in tool
Alias "write", "shell", "aws" Shorthand for built-in tools
MCP server "@git" All tools from a server
MCP tool "@git/status" Specific tool from a server
Wildcard "*" All tools
Built-in wildcard "@builtin" All built-in tools only
No matcher (omitted) Applies to all tools
Stop Hook - The stop trigger does not use matchers. It fires once when the assistant finishes its response, making it ideal for running formatters, linters, or test suites after code generation.

10.2 Hook Configuration Example

"hooks": {
  "agentSpawn": [
    {
      "command": "cat .kiro/project-context.md",
      "timeout_ms": 5000
    }
  ],
  "preToolUse": {
    "fs_write": [
      {
        "command": "echo 'Validating file write...'",
        "timeout_ms": 10000,
        "cache_ttl_seconds": 300
      }
    ]
  }
}
Hook Tool Names - Hook matchers use internal tool names (fs_read, fs_write, execute_bash, use_aws) rather than simplified display names. Default timeout is 30 seconds, configurable with timeout_ms. Results can be cached using cache_ttl_seconds.

11. Subagents & Task Delegation

Subagents are specialized agents that can autonomously execute complex tasks with their own context.

11.1 How Subagents Work

When you assign a task to a subagent, Kiro delegates the work to a separate agent context. This prevents context window bloat and allows parallel execution.

11.2 Key Capabilities

Subagents support autonomous execution with live progress tracking, access to core tools, parallel execution, and results aggregation.

11.3 Controlling Subagent Access

"availableAgents": ["reviewer", "tester", "deployer", "researcher"],
"trustedAgents": ["reviewer", "tester"]

// reviewer and tester run without permission prompts
// deployer and researcher require approval

11.4 The Delegate Tool

For long-running tasks, use the delegate tool for background agents running asynchronously.

12. Planning Mode

Kiro CLI includes a built-in Plan Agent for breaking down complex tasks into structured implementation plans. The Plan Agent operates in read-only mode.

12.1 When to Use Planning Mode

Use for large feature implementations, refactoring projects, architecture decisions, or any complex task.

12.2 How It Works

The Plan Agent can read files, search symbols, and explore your codebase structure to produce structured plans.

13. Experimental Features

Use the /experiment command to toggle cutting-edge features.

13.1 Knowledge Management

Persistent context storage and retrieval with semantic search capabilities.

kiro-cli settings chat.enableKnowledge true
kiro-cli settings knowledge.maxFiles 10000

13.2 TODO Lists

kiro-cli settings chat.enableTodoList true
/todo resume

13.3 Thinking Tool

Shows the AI's step-by-step reasoning process.

kiro-cli settings chat.enableThinking true

13.4 Checkpoints

Session-scoped checkpoints for tracking file changes.

kiro-cli settings chat.enableCheckpoint true

13.5 Tangent Mode

Create conversation checkpoints to explore side topics without disrupting main flow.

kiro-cli settings chat.enableTangentMode true

13.6 Delegate (Background Agents)

Launch and manage asynchronous task processes in parallel.

14. Agent Client Protocol (ACP)

Kiro CLI implements ACP, an open standard for AI agents to work with any compatible editor.

14.1 What is ACP?

ACP provides standardized agent-editor communication via JSON-RPC over stdin/stdout, similar to LSP.

14.2 Starting ACP Mode

# Start Kiro as an ACP agent
kiro-cli acp

# Start with a specific agent configuration
kiro-cli acp --agent my-agent
Use full paths — IDEs typically don't inherit your shell's PATH variable, so kiro-cli alone may fail. Find your full path with which kiro-cli (usually ~/.local/bin/kiro-cli) and use that in all IDE configs below.

14.3 Supported ACP Methods

Kiro supports standard ACP methods plus extensions for slash commands, MCP tools, and session management:

Method Purpose
initialize Exchange capabilities between editor and agent
session/new Create a new chat session
session/load Load an existing session
session/prompt Send a prompt to the agent
session/cancel Cancel an in-progress operation
session/set_mode Switch agent configuration
session/set_model Change the Claude model

Sessions persist to ~/.kiro/sessions/cli/ as JSON metadata and JSONL event logs, so you can resume from any editor.

14.4 Setting Up in VS Code

Step 1: Install the ACP Client extension from the VS Code Marketplace (by Formula Hendry), or search for "ACP Client" in the Extensions panel.

Step 2: Open your VS Code settings.json (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)") and add:

{
  "acp.agents": {
    "Kiro Agent": {
      "command": "/full/path/to/kiro-cli",
      "args": ["acp"],
      "env": {}
    }
  }
}
Find your path — Run which kiro-cli in your terminal and replace /full/path/to/kiro-cli with the result (e.g., /Users/yourname/.local/bin/kiro-cli).

Step 3: Open the ACP Client panel from the Activity Bar (look for the ACP icon on the left sidebar).

Step 4: Click Kiro Agent to connect, or use the Command Palette (Ctrl+Shift+P) and run ACP: Connect to Agent.

You can now chat with Kiro directly inside VS Code. It has full access to your workspace files and tools.

14.5 Setting Up in JetBrains IDEs (WebStorm, PhpStorm, IntelliJ)

This works identically in WebStorm, PhpStorm, IntelliJ IDEA, and all other JetBrains IDEs.

Step 1: Open the AI Chat tool window (usually on the right sidebar). If you don't see it, go to View → Tool Windows → AI Chat.

Step 2: Click the settings gear icon in the AI Chat panel and select "Add Custom Agent".

Step 3: This opens (or creates) the file ~/.jetbrains/acp.json. Add the following configuration:

{
  "agent_servers": {
    "Kiro Agent": {
      "command": "/full/path/to/kiro-cli",
      "args": ["acp"]
    }
  }
}

Step 4: Save the file. Back in the AI Chat panel, click the model/agent dropdown and select Kiro Agent.

Kiro now appears as an option in the AI Chat mode selector across all your JetBrains IDEs.

Using a specific agent — To launch Kiro with a custom agent configuration, change the args to ["acp", "--agent", "my-agent"] in either VS Code or JetBrains configs.

15. Managing Prompts

Kiro CLI supports reusable prompt templates.

15.1 Using Prompts

/prompt list
/prompt my-review-template

15.2 Conversation Persistence

/save my-session-name
/load my-session-name

16. Configuration & Settings

Kiro CLI provides extensive customization through a layered settings system.

16.1 Configuration Scopes

Scope Location Priority
Global ~/.kiro/ Lowest
Project .kiro/ Medium
Agent Agent config file Highest

16.2 Managing Settings

kiro-cli settings list
kiro-cli settings list --all
kiro-cli settings telemetry.enabled true
kiro-cli settings chat.enableKnowledge true
kiro-cli settings chat.enableThinking true
kiro-cli settings chat.enableTodoList true
kiro-cli settings chat.enableCheckpoint true

17. CLI Commands Quick Reference

A complete reference of all CLI commands and their common options:

Command Description
kiro-cli Start a chat session (default)
kiro-cli chat Explicitly start a chat session
kiro-cli chat --agent name Start chat with a specific agent
kiro-cli agent list List all available agents
kiro-cli agent create name Create a new agent
kiro-cli agent edit name Edit an existing agent
kiro-cli settings list View current settings
kiro-cli settings key value Set a configuration value
kiro-cli mcp add --name name Add an MCP server
kiro-cli acp Start ACP mode for IDE integration
kiro-cli chat --resume Resume last conversation in current directory
kiro-cli chat --resume-picker Interactive session picker for resuming
kiro-cli doctor Diagnose and resolve common issues
kiro-cli issue Report a bug with system info
kiro-cli uninstall Uninstall Kiro CLI (macOS)
kiro-cli theme [dark|light|system] Set or view the terminal theme
kiro-cli inline [enable|disable|status] Manage inline suggestions
kiro-cli --version Show installed version

18. Agent Steering

Steering files provide persistent project knowledge through markdown documents, enabling consistent AI-guided code generation without repeating conventions in every conversation. Think of them as always-on context that shapes how Kiro understands and works with your codebase.

Steering File Priority & Merge Flow Team / MDM Pushed via Group Policy or central repo download Priority: Lowest Global Steering ~/.kiro/steering/*.md Personal preferences Priority: Medium Workspace Steering .kiro/steering/*.md Project-specific standards Priority: Highest Merged Context Kiro Agent Foundational & Custom Steering Files product.md Business context tech.md Stack & constraints structure.md File organization custom-*.md API, testing, security...

18.1 Steering File Scopes

Scope Location Purpose
Workspace .kiro/steering/ Project-specific patterns and standards (highest priority)
Global ~/.kiro/steering/ Personal preferences that apply across all workspaces
Team Distributed via MDM / Group Policy Organization-wide standards pushed to global steering
Priority - When workspace and global steering files conflict, workspace-level steering takes priority. This lets teams enforce project-specific standards while developers keep personal preferences globally.

18.2 Foundational Files

Three core steering files establish baseline context for any project:

File Purpose Example Content
product.md Product context Product purpose, target users, key features, business objectives
tech.md Technical stack Frameworks, libraries, tools, infrastructure constraints
structure.md Code organization File layout, naming conventions, architecture patterns
# Example: .kiro/steering/tech.md
## Tech Stack
- **Runtime**: Node.js 20 LTS
- **Framework**: Next.js 15 with App Router
- **Database**: PostgreSQL via Prisma ORM
- **Testing**: Vitest for unit tests, Playwright for E2E
- **Styling**: Tailwind CSS with shadcn/ui components

## Conventions
- Use server components by default; add "use client" only when needed
- All API routes return JSON with { data, error } envelope
- Environment variables must be validated at startup with zod

18.3 Custom Steering Strategy

Create specialized files addressing specific domains your team cares about:

Best Practices for Steering Files

Keep files focused on single domains. Explain the reasoning behind standards, not just the rules. Include code examples and before/after comparisons. Never embed API keys or secrets. Review steering files during architecture changes - treat updates like code reviews.

18.4 AGENTS.md Support

Kiro supports the AGENTS.md standard for steering directives. Place an AGENTS.md file in ~/.kiro/steering/ or your workspace root and it will be automatically included without explicit configuration.

Custom Agents - When using custom agents, steering files are not automatically included. You must explicitly add them via the agent's resources configuration:
{
  "resources": ["file://.kiro/steering/**/*.md"]
}

19. Autocomplete & Inline Suggestions

Kiro CLI provides two AI-powered terminal assistance features that work independently: an autocomplete dropdown menu and inline ghost-text suggestions. Both support hundreds of popular CLI tools.

Two Independent AI-Powered Assistance Systems $ git checkout -b feat Autocomplete Dropdown feature/auth branch feature/api-v2 branch feature/dashboard branch fix/login-bug branch Navigate: Arrow keys | Select: Tab/Enter Inline Ghost Text $ git checkout -b feat ure/auth-oauth2 ghost suggestion Right Arrow or Tab to accept Keep typing to ignore suggestion These two systems work independently

19.1 Autocomplete Dropdown

A graphical menu appears to the right of your cursor as you type, showing available options, subcommands, and arguments. Navigate with arrow keys and press Tab or Enter to select.

Autocomplete is enabled by default after installation. It works with your regular terminal - just start typing any supported command.

Supported Tools

Category Tools
Version Control git (all subcommands, branches, remotes)
Containers docker, docker-compose, kubectl
Package Managers npm, yarn, pnpm, pip, poetry, conda, gem, bundle
Cloud aws, terraform
Language Tools go, cargo, python, node
System ls, find, grep, apt, brew, yum, and more

19.2 Inline Suggestions

Gray "ghost text" appears directly on the command line as you type, offering full command completions based on context. Press the right arrow key or Tab to accept, or keep typing to ignore.

# Manage inline suggestions
kiro-cli inline enable              # Activate
kiro-cli inline disable             # Deactivate
kiro-cli inline status              # Check current state
kiro-cli inline set-customization [ARN]   # Set custom model
kiro-cli inline show-customizations       # List customizations

19.3 Configuration & Themes

# Enable or disable autocomplete
kiro-cli settings autocomplete.disable false   # Enable (default)
kiro-cli settings autocomplete.disable true    # Disable

# Theme management
kiro-cli theme dark       # Dark theme
kiro-cli theme light      # Light theme
kiro-cli theme system     # Follow system preference
kiro-cli theme            # View current theme
kiro-cli theme --list     # List all available themes
Troubleshooting - If autocomplete isn't working, verify your installation with kiro-cli --version, check that it isn't disabled, restart your terminal, and try a different shell (bash, zsh, or fish are supported).

20. Tips & Best Practices

20.1 Getting the Most from Kiro CLI

20.2 Security Best Practices

20.3 Troubleshooting

Kiro CLI includes built-in diagnostics to help resolve common issues:

# Run the diagnostic tool to identify and resolve issues
kiro-cli doctor

# Report a bug with system info automatically attached
kiro-cli issue
Problem Solution
MCP server connection failures Verify prerequisites are installed (e.g., uvx, npx). Check /mcp for server status.
Permission errors Validate API tokens and keys. Re-authenticate with kiro-cli if your session expired.
MCP config not loading Validate JSON syntax. Check file is at .kiro/settings/mcp.json (workspace) or ~/.kiro/settings/mcp.json (global).
Tool names exceed 64 characters MCP tool names (including server prefix) must be ≤ 64 chars and match ^[a-zA-Z][a-zA-Z0-9_]*$.
Autocomplete not appearing Check kiro-cli --version, verify not disabled, restart terminal, try different shell.
glibc version too old Use the musl-based version (-musl.zip) or upgrade your Linux distribution.

20.4 Useful Resources